ISS Overhead Notifier
The ISS Overhead Notifier is a Python automation that emails you whenever the International Space Station is passing overhead and it's dark enough to see it. It pulls live ISS coordinates from the Open Notify API and cross-references them with real-time sunrise/sunset data to make sure the alert is actually useful. The project ships in two versions: the original course build as a reference point, and a refactored advanced build that runs serverlessly on GitHub Actions every five minutes — no Raspberry Pi, no VPS, nothing to maintain.
Quick Facts
Overview
Problem
ISS passes are short — typically two to six minutes — and happen at unpredictable times across the day and night. The only way to catch one is to either check a tracking site constantly or set up something that watches for you. Manual checking is tedious enough that most people just miss passes entirely, and the common suggestion of "run it on a Raspberry Pi" adds hardware, power, and maintenance overhead that most beginners don't want to deal with. There's also a real credential-safety problem with course exercises like this one: the original code stores email passwords as plain string literals, which can easily end up in a public git repo without the developer realising.
Solution
The advanced build is a single-run Python script that checks two public APIs — Open Notify for the ISS's current lat/lon, and Sunrise-Sunset for the current day/night window at the observer's location — then fires a Gmail SMTP notification if both conditions are met. Because it exits cleanly after one check, it plugs directly into a GitHub Actions cron workflow that triggers every five minutes for free on any public repository. The OOP refactor splits concerns into an ISSClient class (all API logic), an EmailNotifier class (all SMTP logic), and a thin orchestrator in main.py — each module is independently testable and replaceable without touching the others. Credentials are loaded from environment variables, either via a local .env file or GitHub Actions repository secrets, using the same os.environ calls in both contexts.
Challenges
The trickiest part of this project wasn't the APIs — it was credential safety. The original course file stored a real Gmail app password as a string literal, which made it into the initial git commit and got pushed to a public GitHub repo before the problem was caught. Fixing it properly meant doing a full clean rebuild from a temp directory rather than trying to rewrite history with rebase, since the template's recovery procedure explicitly prohibits that path. A second structural challenge was naming: having both an original/ folder on main and an original branch created constant git ambiguity — git checkout original would fail because it couldn't tell which one was meant. Renaming the branch to source resolved this permanently and made the intent clearer.
Results / Metrics
The finished project demonstrates how to chain multiple public APIs together, handle credentials safely across both local and CI environments, and design modules with clear separation of concerns. Migrating from a while True polling loop to a GitHub Actions cron job turned out to be the more interesting architectural lesson — it reframes the script as a stateless function rather than a long-running process, which is both simpler and more robust. If I were extending it further, I'd add a run log to the Actions summary so you can see a timeline of when the ISS was overhead, and possibly filter notifications to only send once per pass rather than potentially emailing multiple times in the same five-minute window.
Screenshots
Click to enlarge.
Click to enlarge.
No screenshots available yet.
Videos
No videos available yet.